home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / utilities / pu023.dms / pu023.adf / TOOLS! / Xicon.Doc.Z / Xicon.Doc
Text File  |  1988-07-08  |  17KB  |  307 lines
  1. c
  2. HH    H  H  H  H  2H  3H  4H  5H  H  H  H  5H  2H  3H  4H  15H  1H   1H  1H  1H  1H  1H  1H  0H 1H  20H    8H        8H  8H  8H  8H  8H  8H  8H  28H        0H        0H  0H  0H  0H  0H  0H  0H  40H  6H  6H  6H  6H  6H  6H  6H  42H      2H  2H  2H  2H  2H  2H  2H  2H  52H  4H  5H  6H  7H  8H  9H 59H  9H  0H 0H 9H  9H  9H  9H  9H  H  H  H  H  H  H  H  H  3H  13H  2H  1H  0H  0H  1H  2H  3H  9H8H  9H  9H  9H  9H  9H  9H  9H  18H  6H  6H  6H  6H  6H  6H  6H  6H  26H  8H  8H  8H  8H  8H  8H  8H  8H  38H  4H  4H  4H  4H  4H  4H  4H  0H  0H  0H  0H  0H  0H  0H  0H  50H  57H  7H  7H  6H  5H  4H  4H 8H 7H  7H  7H  14H       16H   16H   16H   16H   16H   14H       25H       27H   27H   27H   27H   27H   25H       11H   13H   13H   13H   13H   13H   11H   22H   24H   24H   24H   24H   24H   22H   H H H H H H H H H 1H 1H                                                                         9H 9H 9H 9H 9H 9H 9H 9H                                                                 37H                                   37H 37H 37H 37H 37H                                   71H 71H 71H 71H 41H   43H 43H 43H 43H 43H 43H 42H43H 42H 41H 40H 40H 40H 40H 40H 40H 40H 40H 38H 38H 38H  41H        48H 48H 48H 47H  46H 45H 44H 42H 41H 40H 39H 39H 39H 39H 39H 39H                        63H 63H 63H 63H 63H 63H44H                    43H 42H 41H 42H
  3. 
  4.  
  5.              XICON  --   Execute Command File from an Icon
  6.          (c) 1986, 1987 by Pete Goodeve -- All Rights Reserved
  8.    Permission is granted to distribute or modify these programs freely,
  9.    provided that no charge is made for their use, and that this notice
  10.    accompanies them.  For commercial purposes, please contact the author:
  12.                   Pete Goodeve
  13.                   3012 Deakin Street #D
  14.                   Berkeley, Calif. 94705
  16. With this program you can execute a file of AmigaDOS CLI commands
  17. directly from WorkBench, rather than using CLI, simply by double-clicking
  18. an associated icon. A full-screen window is opened to display the output.
  20. This is V2 of XICON, with many new features. You can now do such things as
  21. specify window size (or run without any window), change window title, find
  22. the directory the icon was invoked from, & specify command scripts besides
  23. the one associated with the icon. You also get a Close Gadget on the window.
  24. The text-display program TICON is now incorporated, with improvements.
  26. The straightforward use of XICON is to have a 'project' icon associated
  27. with a script file of CLI commands. When you double-click the icon, the
  28. commands in the file will be executed. A full-screen window is opened to
  29. display their output.  The window will remain open when the script is 
  30. finished until you click on the Close gadget or type a control-C (or -D).
  32. "Tool Types" can be added to the icon's info. For example, the window can
  33. close automatically by setting the ToolType 'MODE=closewindow' in the icon.
  34. If the commands have no output that you need to see, use "'MODE=nowindow'.
  35. To set size, use the Tool Type 'WINDOW=...'. To change title, use 'TITLE='.
  37. You also have the option of executing commands from the ToolTypes lines
  38. of the icon itself, if you specify them with the 'CMD=...' ToolType.
  39. You can specify additional command scripts (which will be executed before
  40. the one associated with the icon) with 'SCRIPT=...'.  You can include a 
  41. remark to be displayed in the window with 'REM=...', or a text file with
  42. 'TEXT=...'.  You can include as many of THESE Tool Types as you like; they
  43. are processed in sequence. The sequence may include a wait for a signal
  44. from the user with 'PAUSE'.
  46. The icon you click must always have a file associated with it, but this
  47. needn't NECESSARILY be a list of CLI commands; if you set 'MODE=noscript',
  48. it can be any type of data; you can operate on it if you want with commands
  49. in the ToolTypes list. If you set 'MODE=text' it will be treated as a simple
  50. text file to be displayed a page at a time in the window.
  52. The Tool Type 'LOCDIR=..' lets you specify a file in a known DIR that will
  53. be written with the complete pathname of the directory containing the icon.
  55. A 'choice' mechanism has been added to this version. You can take special
  56. action if the sequence has been aborted. See the description of the 'ABORT-'
  57. Tool Types below. You can use the 'EXISTS=' Tool Type to see if a file 
  58. exists, and abort if it does not.
  60. You can select more than one icon at a time, by holding down the SHIFT key
  61. as you click on each. Only DOUBLE-click on the LAST selection (or use the
  62. WorkBench menu "Open" item)
  63.  
  64. Text Display:
  66. When XICON is in the text display mode ('MODE=text' or 'TEXT=...') the file
  67. is displayed a window-full at a time. It will also pause if a form-feed
  68. character is encountered. To continue, type any key or click in the bottom
  69. window border. You can abort display by either clicking in the Close gadget'
  70. or typing control-C; it will immediately proceed to the next operation if 
  71. any. You will have to repeat the action to exit XICON on the last operation.
  72. This is different from the immediate exit that follows a click on the Close
  73. gadget in response to a PAUSE Tool Type.
  74.  
  75. Setup:
  77. You can install Xicon itself in any convenient directory on the same disk:
  78. Whichever directory you use, the icons that are going to invoke it must
  79. have a matching pathname as their DEFAULT TOOL (see below).
  81. You can put an icon and its associated file in any "drawer" that you can
  82. open under WorkBench. The file must have the same name as the icon (without
  83. the '.info' extension). Each icon must be of type 'PROJECT' with a DEFAULT
  84. TOOL string specifying a path to Xicon. If it is in the same directory,
  85. 'xicon' will suffice, otherwise you must use the complete pathname. A full
  86. pathname always begins with "device name", which is either an actual device
  87. (e.g. DF0:) or an assigned name (e.g. SYS:). If the icons are on the same
  88. disk as xicon, the device can be simply ":" (Example- :XICON)
  89.  
  90. Command Scripts:
  92. There are many ways to generate Command Script files with their icons.
  93. One approach is to duplicate an existing icon, then go to the CLI and
  94. modify the text file using your favorite text editor. If xicon is not in
  95. the appropriate directory, you will have to change the Default Tool in the
  96. icon to the correct pathname. Alternatively you can create the text file
  97. first, then use CLI to copy a project icon and modify it as necessary.
  98.  
  99. Modifying an icon:
  101. All the changes you NEED to make to an icon can be done with the 'Info'
  102. item in the WorkBench Menu. Select the icon you want to modify by clicking
  103. on it, press the right mouse button, & select 'Info' from the 'WorkBench'
  104. menu. This brings up an information window for that icon.
  106. To set the DEFAULT TOOL, click in that gadget and type in the string.
  108. To enter a new TOOL TYPE, click first on the ADD gadget, then click in the
  109. string gadget and type it in.  If you want to insert it into an existing
  110. set, use the arrow gadgets on the left to move to the desired point first.
  111. Use the DEL gadget to remove a line completely.
  113. When you are done, click in the SAVE box to preserve the changes. There is
  114. a bug in WorkBench1.2: Tool Types you enter into the icon may get messed
  115. up, causing the next string to be tagged on. The only fix seems to be
  116. to go back to Info, re-edit all your Tool Types, and try saving again.
  118. MODE Setting: You can alter Xicon's parameters by setting the ToolType: MODE
  120. 'MODE=closewindow' The window self-closes on completion of all commands.
  121.  
  122. 'MODE=nowindow' No window is opened, all msgs are thrown away to "NIL:"
  123.  
  124. 'MODE=noscript' prevents Xicon from trying to read commands from
  125.       its associated file. When the 'CMD=' Tool Type supplies the commands.
  126.  
  127. 'MODE=text' Displays the associated file as text, a full window at a time.
  129. Only one MODE entry will be recognized in the Tool Types array, so if you
  130. want more than one of the above options, you must specify them separated
  131. by the vertical-bar character, for example: 'MODE=noscript|closewindow'.
  132.  
  133. Modifying the Window:
  135. You can specify the size, position and title of the window that XICON opens
  136. by setting the Tool Type 'WINDOW=xxx/yyy/www/hhh/Title', where xxx and yyy
  137. are the co-ordinates of the top left corner, www and hhh are width and 
  138. height, and Title is the desired name for the window. To change the TITLE
  139. at ANY time in the sequence, use the ToolType 'TITLE=title string'. You can
  140. use this more than once in a sequence
  141.  
  142. Commands in the Icon:
  144. Instead of a script file, you can specify commands directly in the Icon Tool
  145. Types array, with the 'CMD=Command string' format; Ex: 'CMD=list df1:work'
  147. Include as many of these as you like. They will be executed in sequence,
  148. but each by a separate CLI process, so you can't use a command to set
  149. parameters like stack size or current directory for the ones that follow.
  150. A Command Script file on the other hand is executed completely by one
  151. process, so settings are inherited.
  153. If you want to execute additional command script files BEFORE the one
  154. associated with the icon (if any), use 'SCRIPT=filename'. 'filename' may
  155. be the name of a script file in the same directory as the icon, or the
  156. complete pathname of such a file. These may be interspersed with 'CMD=..'
  157. lines, etc, & are executed sequentially. Each SCRIPT= is a separate process.
  158.  
  159. Finding the Directory:
  161. An unfortunate problem of executing commands is that the new CLI has no idea
  162. of which directory it was called from. To overcome this, XICON has the Tool
  163. Type 'LOCDIR=filename'. If you include this in the icon, the specified file
  164. will be created and filled with a text string giving the complete path name
  165. of the directory containing the icon. Commands in the script can refer to
  166. this file to take appropriate action.  The string is always enclosed in
  167. quotes, and has a newline character at the end.  DOS commands such as CD
  168. or DIR can read this string simply by redirecting their input and prompting
  169. with '?' (for commands which don't need any output, you can suppress the
  170. prompt by redirecting output to NIL:). For example, include in the icon info:
  172. LOCDIR=RAM:my_icon_dir
  174. then start your script with the sequence:  CD <RAM:my_icon_dir >NIL: ?
  176. and you are now working in the right directory.  For neatness, you should
  177. also delete the file before you end the command script. Choose unique file
  178. names if you plan to be running more than one icon at a time.
  179.  
  180. Other Tool Types:
  182. You have various other actions that you can request with Tool Type strings.
  183. They may be intermixed with the previous types.
  185. 'TEXT=filename' displays the specified file in the window (like MODE=text)
  186.  
  187. 'REM=text' displays the text line as a remark at that point.
  188.  
  189. 'PAUSE'  (No "="!) pauses the sequence at that point, Continue by clicking
  190.    in the bottom border of the window or typing any key. If you click in
  191.    the Close gadget, or type control-C, all remaining Tool Type commands
  192.    will be skipped except 'RESTORE', & those with the 'ABORT-' prefix.
  193.  
  194. 'RESTORE' is only relevant if the sequence has been aborted. If encountered,
  195.    it removes the abort condition; Tool Type commands and the file
  196.    associated with the icon will be executed as normal.
  197.  
  198. 'EXISTS=filename' will set the abort condition  if the specified
  199.    file doesn't exist.
  200.  
  201. The 'abort' condition:
  203. If the Close gadget is clicked or control-C typed in response to a PAUSE,
  204. or if an 'EXISTS=...' Tool Type fails, the abort condition will be set;
  205. all further normal Tool Type commands, and execution or display of the
  206. file associated with the icon, are suppressed. If the 'RESTORE' Tool Type
  207. is encountered, normal operation is restored.
  209. There are a set of alternative Tool Type commands, corresponding to
  210. the normal ones but prefixed with 'ABORT-', that will ONLY be executed
  211. if the abort condition has been set:
  213. ABORT-REM=...
  214. ABORT-CMD=...
  215. ABORT-TEXT=...
  216. ABORT-SCRIPT=...
  217. ABORT-PAUSE
  219. Abort-Pause behaves JUST like normal PAUSE; if you click in the Continue
  220. gadget or type a key other than control-C the abort condition is REMOVED.
  221.  
  222. Sequence of Tool Types:
  224. Remember the difference between the Tool Types that control the environment
  225. ('MODE=...','WINDOW=...', etc.) and those that are scanned in sequence. The
  226. first appearance of each of the former will be recognized at startup ONLY;
  227. so they won't be affected by abort conditions. They may be placed anywhere
  228. in the set of Tool Types, in any order, and they will still be recognized.
  229.  
  230. Tool Types processed at startup are:
  232. MODE=
  233. WINDOW=
  234. LOCDIR=
  235.  
  236. Those processed in sequence are:
  238. CMD=
  239. REM=
  240. SCRIPT=
  241. TEXT=
  242. TITLE=
  243. PAUSE
  244. RESTORE
  245. EXISTS=
  246. ABORT-...
  248. If you misspell a Tool Type name, it will simply be ignored.
  249.  
  250. Caveats:
  252.    An annoying defect is that the "Execute()" system call used by xicon
  253. loses track of the current directory when invoked by a WorkBench program
  254. (it switches to DF0:). The LOCDIR Tool Type has been added to overcome this
  255. problem, but if you don't use this you will have to specify full pathnames.
  257. The "Execute" referred to above is NOT the DOS "EXECUTE" Command. Actually,
  258. this system call (and therefore xicon) requires the DOS "RUN" command be in
  259. the "C:" directory for its operation. Because xicon's method of calling
  260. Execute() sets up the command file as the input stream, the output window
  261. cannot be used as a console.  So if a command needs keyboard input it must
  262. open its own using I/O redirection, e.g.: mycommand <CON:0/100/150/50/input
  263. You might also want to try "EXECUTE CON:0/100/150/50/exec"--or whatever you
  264. have renamed that command as. (To get out of the mini-CLI you just created,
  265. use 'control-\'.)  If you really want to create a full new CLI, the best
  266. method is 'NEWCLI FROM filename'
  268. The initial stack size is always 4000 bytes.  You can change this in your
  269. command script with a STACK command.  Note that the STACK gadget in the icon
  270. Info window has no effect, except on XICON itself.
  272. You cannot interrupt a command sequence with control-C or control-D,
  273. although output can be paused with the space bar in the usual way. Don't
  274. write a command file that can get "stuck" or you'll never close the window!
  276. DOS won't let you use IF, SKIP, QUIT, etc, in these command files. Of course
  277. you can use EXECUTE on a subsidiary script file, or 'NEWCLI FROM scriptfile'.
  279. You can use the RUN command from a command script, of course, but any output
  280. from the process started by RUN is thrown away instead of being displayed.  
  282. If you find these programs useful, please pass them around freely, and;
  283. I would be pleased no end if you decided to send me $5 or $10.  I'm also
  284. glad to get comments -- positive OR negative.
  285.  
  286. OTHER SHAREWARE BY THE AUTHOR: ($25.)
  287.     Smart Input Line Interpreter "Sili(Con:)"
  288. It lets you enter your commands with full cursor editing facilities.
  289. Previous commands are kept in a VISIBLE history list; you can recall
  290. commands for re-execution/re-editing, by using the arrow keys or clicking
  291. on them. This occurs in its own window. You can enter & edit commands while
  292. previous ones are running. If you have commands you are using repetively,
  293. you can call them directly from the history window by double-clicking them.
  294. You can push the command window out of the way, or bring it back with 
  295. one keystroke. Also, you can invoke command scripts without typing EXECUTE.
  297. It is downloadable from several of the commercial services, and is also
  298. on Fish disk #50. You can also order it directly, for $25 plus $3 p&p 
  299. (Calif. residents add 6.5% sales tax) from:
  301. Winners Circle Systems
  302. 2618 Telegraph Avenue
  303. Berkeley, California 94704
  304. [Tel: (415) 845-4814]
  306.         CLICK CLOSE GADGET, OR USE CTRL-C OR CTRL-D TO EXIT  
  307.